Amiga Plus 2002 #11/Amiga Plus CD - 2002 - No. 11.iso/CD_System/AmigaAMP/AmigaAMP.readme

Text File | 2002-08-17 | 27KB | 681 lines

Short:    MPEG audio player with GUI (68k/PPC)
Uploader: Thomas Wenzel ([e-mail])
Author:   Thomas Wenzel ([e-mail])
Type:     mus/play
Version:  2.9


AmigaAMP makes use of the following 3rd party code
--------------------------------------------------
AHI Audio System © Martin Blom
MHI © Paul Qureshi, Dirk Conrad and Thomas Wenzel
mpega.library © Stephane Tavenard
asyncio.library © Magnus Holmgren
prelude.library © A.C.T.
sndfile.library © Erik de Castro Lopo, ported by Sigbjørn Skjæret
popupmenu.library © Henrik Isaksson
guigfx.library © Timm S. Müller
AmigaAMP preferences © Daniel Westerberg
MPEG Layer-3 technology licensed by Fraunhofer IIS and Thomson Multimedia


Homepage
--------
http://www.amigaamp.de/

EMail
-----
[e-mail] (German and English spoken)


Disclaimer [NEW!]
-----------------
AmigaAMP is freeware! It's nothing more than the result of my more or less
good hobby programming skills. I have very little time for future
development and almost no time for support. You still may send me e-mails
with bugreports and ideas but they will probably remain unanswered.

To put it short: It works on my machine. If it doesn't on yours - bad luck!
But it's free!


Introduction
------------
You want an audio player that really makes use of your high spec Amiga?
Here it is!

AmigaAMP is a GUI based MPEG audio player using mpega.library on the 68k
processor or the amp decoding engine in the PPC version. Additionally it
can make use of sndfile.library to play AIFF, WAV and 8SVX files. Playback
is done through the AHI audio system.

If you've got problems not related to the user interface but with AHI,
AsyncIO or mpega.library, PLEASE contact the corresponding author directly.
I wouldn't be able to help you in this case.

Important: AmigaAMP is optimized for visual appearance and accuracy, not
for extremely low cpu load!

What does that mean? Well...if there's a percussion hit, you see it on the
analyzer immediately. Not half a second later, not half a second earlier.
People who say "I don't care about this, I just want to see some movement in
the display" should use another player :-)

However, if anyone has a fast PowerPC and a fast graphics card which ain't
got nothing to do but run the PPC version of Heretic-II, AmigaAMP is just
right :)


Requirements (not included in this archive!)
--------------------------------------------
AmigaOS 3.0 or higher
68030-50MHz processor or better
mpega.library      (Aminet:util/libs/mpega_library.lha)
asyncio.library    (Aminet:dev/c/AsyncIO.lha)
AHI audio system   (Aminet:mus/misc/ahiusr.lha)

 For most of the skins:
 - picture.datatype v43
 - ilbm.datatype v44
 - bmp.datatype v40

 For the guigfx loading routines (optional)
 - guigfx.library v16
 - render.library v30

 For popup menus (optional)
 - popupmenu.library v9

 For AIFF, WAV and 8SVX support (optional)
 - sndfile.library v1


An important note on graphics patches
-------------------------------------

There are numerous programs around that patch functions of graphics.library
to make some routines faster or to redirect calls to CyberGraphX. I strongly
recommend NOT to use those patches but to upgrade to *real* AmigaOS 3.1 and
use a graphic card instead. GFXPatch made AmigaAMP think it was running
under 3.1 and as a result some other functions didn't work as expected.
PatchWPA8 caused deadlocks because several subprocesses of AmigaAMP will
call the patched routine at the same time. NewWPA8 has been reported to
work so far but I won't rely on that! Now get a soundcard, get a graphics
card, get AmigaOS 3.1 and stop bothering me! :-)

An important note on file systems
---------------------------------

Some filesystems, especially network-filesystems tend to have problems with
asyncio.library. If you experience problems like sudden hangups during
playback or no playback at all when skipping to the next track, try
switching off asyncio.library by setting the NOASYNCIO ToolType. I've also
heard that some WarpUP versions of asyncio.library tend to cause all sorts
of problems. If in doubt use the 68k version!


Recommended
-----------
Prelude soundcard (old but good! :))
PowerUP and ppc.library v46 / WarpUP and powerpc.library v15
AmigaOS 3.1 (OS3.1 or CGFX is needed for the internal spectrum analyzer!)


Features
--------
 - FREEWARE!  No nag requesters and no expiry date!
 - GadTools based font sensitive user interface
 - Alternatively WinAMP compatible user interface
 - Fast, synchronous spectrum analyzer (almost no latency)
 - PPC based graphic equalizer
 - Workbench application (you can drop icons on its window)
 - Easily configurable
 - AHI device-level access (uses default audio mode automatically)
 - ID3 tag editor (artist, title, albm, etc.)
 - Visualisation plugin system
 - Shoutcast support (internet radio)

 - support for:                                         -> file needed:

   * hardware based decoders
     -----------------------
     - MPEGit (MPEG audio decoder module for Prelude)   -> libs:prelude.library
     - MHI compatible devices                           -> libs:mhi/mhixxx.library

   * software based decoders
     -----------------------
     - internal PowerUP decoding engine (amp 0.7.6)     -> Engines/Internal
     - mpega.library (either PowerUP, WarpUP or 680x0)  -> libs:mpega.library
     - external decoder plugin (based on whatever)      -> Engines/External


Limitations
-----------
 - No realtime spectrum when using AmigaOS 3.0 without gfx card
 - No visualisation when using hardware based decoders


Directory structure
-------------------
 * AmigaAMP
   The main executable, the docs and the icons reside here.

 * AmigaAMP/Engines
   This directory contains AmigaAMP's 'internal' PowerUP decoding
   engine. Any third party engines (called 'external') must be copied
   here.

 * AmigaAMP/Plugins
   Put all your visualisation plugins in here

 * AmigaAMP/Skins
   This is the place for all the graphic extensions (skins)

There are two versions of the main executable:

 - AmigaAMP        compiled for 68060 (runs on 040, too)
 - AmigaAMP.NoFPU  compiled for processors without FPU

History
-------
v2.9  - Improved shoutcast streaming routines with better buffering
        and metadata display (current track)
      - faster scrolling through the playlist
      - new arexx command: ADD
      - implemented "add URL" requester
      - name of skin to load now being stored in amigaamp.prefs
        (use tooltype SKIN to override)

v2.8  - support for multiple plugins at once
      - streaming audio support for streams received through the
        PIPE-handler
      - extended playlist saving format, storing the duration as well
      - new config save format (readable text)
      - autoplay of opened files (configurable)
      - popupmenu.library autodetection -> enable popup menus at certain
        places
      - new AREXX commands: SEEK, DECVOLUME, INCVOLUME, REPEAT
      - MPEG 2.5 support built into PPC engines (experimental!)
      - AIFF, WAV and 8SVX support through sndfile.library
      - MHI support for hardware based MPEG audio decoders
      - Shoutcast/Icecast streaming capability  (experimental!)

v2.7  - skin support for playlist window
      - non-interrupted playback when opening the config window
      - waveform data is now available for plugins as well
      - shift-click in the analyzer display changes its resolution
      - pulldown menus for skins and plugins
      - during uniconify the skin will only be reloaded if nessecary
      - new AREXX commands: FFWD and REW
      - playlist loading via AREXX fixed
      - external decoder type will be displayed in the engine cycle gadget
      - fixed some bugs in the backdrop/immovable window routines
      - the analyzer peak dots will now be displayed in the right color
      - now using guigfx for loading the images, set ToolType NOGUIGFX if
        you don't want that
      - asyncio.library usage can be disabled by setting NOASYNCIO
      - better click reduction for MPEGit
      - filenames being passed to AmigaAMP when starting it a second time
        now may contain spaces
      - better detection of MPEG streams that have a text header in front
        of the stream data

v2.6  - graphic EQ (PowerPC only!)
      - faster skin loading
      - windows can be set to backdrop and immovable
      - priority slider now affects PowerUP decoder priority as well
        but only after you quit and restart the program
      - finer pitch-control: now four steps per semitone
      - new tooltype PLAYLIST for default playlist to load at startup
      - warning requester if no stereo++ mode ist selected for AmigaAMP's
        AHI unit
      - Dropping files on the playlist window now adds them to the list
        instead of replacing the old ones

v2.5  - removed a routine that caused problems with some AHI installations
        (SP2)
      - less clicking noise when starting MP3 playback on MPEGit (SP1)
      - fixed a bug in the playlist saver which caused the filenames to
        be truncated sometimes
      - extended plugin data available including title, artist and more
      - Fixed the PowerUP based MP2 decoder (thanks to Jan Uerpmann!)
      - new decoder plugin system, can be configured from within AmigaAMP
      - sealed some memory leaks
      - Ahi.device will be closed every time you hit the stop button. If
        you don't want this to happen, tick "keep AHI open" in the config
        window.
      - ID3v2 support (currently read-only)
      - better variable-bitrate (vbr) mpeg support
      - ready for graphic eq, but not yet built in
      - NewMouse support (Aminet:hard/misc/NewMouse11.lha)

v2.4  - Due to lack of time it may take a while until I can answer your
        email. Perhaps I won't be able to answer it at all :-(
        You can be sure that I _read_ each and every mail. I'm always
        happy to receive feedback :)
      - visualisation plugins didn't receive data when AmigaAMP was run
        in GadTools mode -- fixed that
      - yet another bug in the ID3 loader/saver detected and eliminated
      - new fullscreen plugin added to the distribution archive
      - built in visualisation now supports cybergraphics as well

v2.3  - reworked the skin display once again
      - 68k based spectrum analyzer that works with mpega.library, too
        (68060 processor and/or PPC version of mpega needed)
      - visualisation plugin system (only makes sense when using the
        internal PPC decoder)
      - fixed a bug that caused some MP3s to be treated as playlists
      - activated shuffle gadget now shuffles the playlist each time
        you start playing the first track
      - included an 060 optimized version

v2.2  - better CyberGraphX compatibility
      - editable playlist including loading and saving (from the menu)
      - time/remain display
      - freaky animation in the bottom right corner :)
      - autoscrolling song/artist text in WinAMP mode
      - skin display while loading on highcolor/truecolor screens
      - random play (shuffle)
      - more alphabetically sorted genres
      - key sensitive genre requester
      - pitch shift (+ and - keys on numeric keypad, * resets speed)
      - improved PUBSCREEN and SCREENMODE capabilities
      - fixed internal crossfader
        Start two aamps and hold shift while dragging the volume slider
      - support for 'nums_ex' and 'volbar' named skin images

v2.1  - configurable playback buffer size (should cure many problems!)
      - fixed a bug that caused truecolor skins to be dithered even on
        truecolor screens
      - Skin pictures can have any extension you like as long as the name
        is correct.
      - Fixed a bug in the PPC loader for 48 kHz MPEGs
      - asynchronous filerequester
      - Skins can be reloaded at any time.
      - auto-play after opening a file if playback was active before opening
      - corrected some skin positions
      - visualisation for the 68k version, too (level meters)
      - MaxFreq finally works

v2.0  - so many changes it was worth bumping the version number :-)
      - position of genre listview gadget fixed
      - fixed bugs when playing mono or 22.05 kHz files
      - digital volume control
      - AREXX interface (see AREXX.readme)
      - automatic detection if another AmigaAMP task is already
        running
      - alphabetically sorted playlist (not editable yet)
      - configurable buffersize
      - WinAMP lookalike GUI (see below)
      - Improved fontsensitivity of old GUI
      - cached taginfo -- will be written when the file is closed

v1.1  - name changed to AmigaAMP
      - PPC version
      - ID3 tag editor
      - commandline support

v1.0  - initial release called MPEGAHI

Getting started (configuration)
-------------------------------
Important! You need a properly installed and configured AHI audio system
to run AmigaAMP. Without a correct setup the sound may be very poor and
AHI will draw too much CPU power!

First of all run the AHI setup program in your Prefs drawer. Select
one of the units from 0 to 3 but not the Music unit. If you don't use
unit 0 for anything already I recommend using that one.

Select one of the "fast stereo++" audiomodes that matches your audio
hardware. For Prelude playback I recommend "Prelude:Fast 16 bit stereo++
realtime".

Now you need to know what sampling rate most of your MPEG files
have. Probably it's 44100 Hz because that's the standard CD rate. If
you have a slow processor you may want to run AmigaAMP in frequency division
mode to reduce CPU load. Have a look at the table below for the recommended
settings.

It is important to set the frequency slider to your mostly used frequency
divided by your chosen frequency divisor. For example, if you're going to
playback lots of 44100 Hz MPEGs and frequency division is 1:2, set the
Frequency slider to 22050 Hz.

If you don't plan to have several programs playing back audio at the
same time, please leave the Channels slider at position 1. The remaining
settings depend on your audio hardware.

Ok, press the "Save" button in the bottom left corner.

Now it's time to configure AmigaAMP itself. If you've chosen another
AHI device than 0, you have to change the AHIUNIT tooltype of AmigaAMP
first. If not, just start it by double clicking on its icon and pop up
the setup window by chosing Config... from the menu.

Set the sliders and checkmarks to the recommended settings, save them using
the menu and close the settings window again.

That's it! AmigaAMP is now configured. You may want to fine-tune the
settings later. The overall performance depends on the speed of mpega.library
AND the the speed of your soundcard's AHI driver.

Recommended settings (tested with Prelude:Fast 16 bit stereo++ realtime)
------------------------------------------------------------------------

          |     Layer 1/2        |        Layer 3
Processor | Quality|FreqDiv|Mono | Quality|FreqDiv|Mono
----------+--------+-------+-----+--------+-------+-----
68040-40  |  high  |  1:2  | off | medium |  1:2  | on
68060-50  |  high  |  1:1  | off |  high  |  1:1  | off
PPC604e   |  high  |  1:1  | off |  high  |  1:1  | off

Note: In fact only the 68k version is affected by these settings.


Advanced settings
-----------------
* Bufsize:
Set the size of the read ahead buffer. Try playing with it until you
get best results. (Normally 16 to 32K is best)
Setting the buffersize to FILE means that the read ahead buffer will
be as large as the current track eliminating all disk access during
play. Attention! This option isn't 100% stable yet!

* TaskPri:
Set the running task priority of AmigaAMP. The recommended value for
uninterrupted playback is 1. God knows what happens if some 3rd party
task rescheduler starts fiddling around with AmigaAMP's internal task
priorities...

* Read ID3 TagInfo
Try to read information about artist, title, etc. Because those are stored
at the end of the file it may slow down loading a bit. If this function
is switched off, TagInfo can neither be edited nor saved!

* Allow multiple instances
Normally when you click on an MPEG file project icon while AmigaAMP is
already playing another one, no second AmigaAMP task will be launched but
the already running task will start playing the new file. This behaviour
can be switched off. You have to start AmigaAMP twice manually and then
save the config with "Allow multiple instances" switched on from both
running tasks.

* Limit volume to 0dB
The volume slider ranges from silence to +6dB volume so that you can boost
more silent recordings. If you don't want to turn the volume above normal
accidentally, you can switch on this option.

* ToolType: MPEGIT
REMOVED! Please use the "Engines" cycle gadget instead.

* ToolType: DIRECTORY
Default directory to display in filerequester.

* ToolType: NOGUIGFX
Because of permanent problems with my method of using datatypes directly
I've changed over to guigfx.library. If this causes problems on your
system, you can always switch back to the old method by setting the
NOGUIGFX ToolType.

* ToolType: NOASYNCIO
Some filesystems, especially over the network, cause problems with
asyncio.library. To revert to the original AmigaDOS routines you can
set NOASYNCIO.

* ToolType/Keyword: SCREENMODE
Tell AmigaAMP to use its own screen. The mode has to be specified in
decimal or hexadecimal format. Hex values have to be preceeded by
<0x> or <$>. Example: SCREENMODE=0x50021303

* ToolType/Keyword: PUBSCREEN
Name of the public screen that AmigaAMP will display its GUI on.
Example: PUBSCREEN=DOPUS.1

* Keyword: STREAM
Treat the given filename as an MPEG stream of infinite length. No wildcards
are allowed in this case and all navigational functions like the position
scroller and ffwd, rew, skip, even stop and play are disabled!

Usage (how to load and play sounds)
-----------------------------------
Most of the buttons should be self-explanatory because they can be found
on almost every CD player or tapedeck. However, as a computer program,
AmigaAMP is based on files, so there may be slight differences. The bottom
line buttons from left to right are:

 - Eject      Stops playback, empties the current playlist and opens a
              requester to select one or more files
 - Skip back  Moves to the previous track in the playlist if there is one.
 - Stop       Simply stops playback. (What else did you expect? :-)
 - Play       Starts playback if there's at least one track in the current
              playlist. If it's not, opens a requester to select tracks.
 - Skip fwd   Moves to the next track in the playlist if there is one.
 - Pause      Pauses playback at the current position

Just above the control button's there's a position slider. As you play
a file, it's button moves from left to right to display the relative
playback position within the current track. You can use the mouse to drag
this slider to a new position.


Shoutcast streaming
-------------------
At the moment there are two alternatives for starting a Shoutcast stream:

1. Open a downloaded Shoutcast playlist file, e.g. from www.shoutcast.com

2. Specify the URL in the commandline but WITHOUT the STREAM keyword, e.g.
   AmigaAMP http://205.188.245.133:8006

Beware! This is a brandnew feature and it's still not 100% finished and
stable yet. I'm working on it :)


Keyboard shortcuts
------------------
CURSOR RIGHT        skip 10s forward
CURSOR LEFT         skip 10s backward
CURSOR UP           increase volume
CURSOR DOWN         decrease volume
SPACE               play/stop
P                   pause
NUM +               increase speed by one semitone
NUM -               decrease speed by one semitone
NUM *               normal playback speed
Z                   skip back one track
X                   play
C                   pause
V                   stop
B                   skip fwd one track
N                   eject

About the WinAMP GUI
--------------------
Since WinAMP v1.80 you can load customizeable textures (so called skins) for
the GUI. The skins consist of several bitmapped pictures together in one
directory and contain the the look of the window itself as well as images
for all the gadgets. Because more and more people ask me to make AmigaAMP
look like WinAMP I now included an alternative GUI routine that can load
those WinAMP skins!

To keep the archive small I'm just including the base skin from now on.

To activate one of those GUIs you have to switch on "Skin display" in the
config window.

Although the pictures all have the extension .iff they can be any format
that you have a datatype for. If you find a working BMP datatype (try
loading the pictures with multiview first) you can even copy WinAMP skins
direcly. AmigaAMP will try to load pictures with different extensions
automatically.


Legal stuff
-----------
AmigaAMP is copyrighted freeware. It may be distributed freely as long as
no modifications are made to the executable and this document. A nominal
fee may be asked to cover distribution costs. If you want to include
AmigaAMP in a commercially distributed software compilation I ask you for
a free copy. This includes "Shareware CDs" as well as computer magazines
with cover disks. In any case please contact me and send me a freebie of
that issue. This freebie has to be an original being identical to the
retail version.

AmigaAMP may not be used for any commercial purposes or included with any
commercial product without the written permission of the author. It may not
be advertised, offered or distributed together or in conjunction with
commercial products. The only exception is the Aminet archive.

AmigaAMP makes use of the MPEG Layer-3 audio compression technology licensed
by Fraunhofer IIS and THOMSON multimedia. The engine being used is amp v0.7
by Tomislav Uzelac.

No responsibilities are taken for damaged speakers, amplifiers, Amigas
or any other components or data involved while using AmigaAMP.

Although I've done some beta testing I can't guarantee that AmigaAMP will
not crash! If you find any bugs, let me know.

Here's the original amp.readme:
-------------------------------
amp MPEG audio decoder readme file (version 0.7.5)
(C) Tomislav Uzelac  1996,1997

amp is free software and can be _used_ freely by anyone. If you want to
do anything else with it, be sure to check the Legal section of this
document for legal issues.

THERE IS NO WARRANTY FOR THIS PROGRAM. Please check out the Legal section
of this document.

1. Introduction
2. Installation
3. Running
4. Feedback
5. Contributing
6. Legal


1. Introduction

amp (Audio Mpeg Player) is an MPEG audio decoder which I originally started
putting together as a side project of the MPEG hardware design project at
FER/Zagreb - just to confirm my knowledge of the standard. It works with
both MPEG1 and MPEG2 audio streams (except for the multichannel extensions
defined in MPEG2), layers 2 and 3.

There is a gui for amp, written in Tcl/Tk by Edouard Lafargue. It is
available at the amp home site ftp://ftp.rasip.fer.hr

Another gui supported is the Sajber Jukebox, written by Joel Lindholm.

The following people contributed their time and knowledge to amp:
Karl Anders Oygard, Ilkka Karvinen, Lutz Vieweg, Dan Nelson,
Edouard Lafargue, Andrew Richards, George Colouris,
Dmitry Boldyrev, Andy Lo A Foe, Thomas Sailer, Justin Frankel

amp home location is
    ftp://ftp.rasip.fer.hr/pub/mpeg/

and the mailing list: send 'HELP' in the body of the message to:
    [e-mail]

If you want to find out more about MPEG, best places to start are
    http://www.mpeg.org
    http://www.mpeg2.de


2. Installation

Installation should be simple enough if amp was ported to your system,
just do a

./configure
make

You can edit the makefile further to suit your system. If configure fails
to make a usable Makefile, you'll _have_ to edit it yourself.

Linux users should try real-time playing support, as described
in doc/realtime.txt. Some people that might pass on this feature are
those with slower machines (i.e. 486's), or SMP systems (see the
doc/linuxrealtime.txt file).
Some versions of the linux C library produce an error when compiling
amp with realtime support. A quick fix is to edit /usr/include/sched.h
and replace _P in the offending line with __P.

./configure --enable-realtime
make
chown root.root amp
chmod u+s amp

... this requires /dev/dsp to be both world readable and writeable. If you
have a special group for people allowed to use the sound device (for
instance, a group called sound), you can do a:

chmod g+s amp

or make your audio card world read/writeable (not recomended)

chmod o+rw /dev/dsp*

3. Running:

'amp -h' gives you usage & options. If your computer is on the slower
side, direct playback might not work, but you can decode it
to .wav or raw pcm and play it later.


4. Feedback

Send in your makefiles, opinions, bugreports, fixes; anything related to this
program. You can also send me unlimited amounts of money, sugar, milk, etc.

If you find any mpeg audio files that amp has trouble decoding, please tell
me about this via e-mail <[e-mail]>.


5. Contributing

Please contribute to amp. If you want to know what is going on in amp
development, you can join the developers mailing list

    [e-mail]

There are certain debugging facilities that I made in amp, but are disabled
in the current release (they are neither nice nor user-friendly). If anyone
enhances them (they are in dump.c) to the point that they're actually
usable I'll be happy to include the changes in the release. I think this
kind of debug output would be very useful to people studying these audio
algorithms.


6. Legal

This software can be used freely for any purpose. It can be distributed
freely, as long as it is not sold commercially without permission from
Tomislav Uzelac <[e-mail]>. However, including this software
on CD_ROMs containing other free software is explicitly permitted even
when a modest distribution fee is charged for the CD, as long as this
software is not a primary selling argument for the CD.

Building derived versions of this software is permitted, as long as they
are not sold commercially without permission from Tomislav Uzelac
<[e-mail]>. Any derived versions must be clearly marked as
such, and must be called by a name other than amp. Any derived versions
must retain this copyright notice.

/* This license is itself copied from Tatu Ylonen's ssh package. It does
 * not mention being copyrighted itself :)
 */

THERE IS NO WARRANTY FOR THIS PROGRAM - whatsoever. You use it entirely
at your risk, and neither Tomislav Uzelac, nor FER will be liable for
any damages that might occur to your computer, software, etc. in
consequence of you using this freeware program.


Tomislav Uzelac
<[e-mail]>